[docs] Move documentation to inline comments: GtkSocket

https://bugzilla.gnome.org/show_bug.cgi?id=611707

diff --git a/docs/reference/gtk/tmpl/gtksocket.sgml b/docs/reference/gtk/tmpl/gtksocket.sgml
deleted file mode 100644 (file)
index f765693..0000000
--- a/docs/reference/gtk/tmpl/gtksocket.sgml
+++ /dev/null
@@ -1,170 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkSocket
-
-<!-- ##### SECTION Short_Description ##### -->
-Container for widgets from other processes
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-Together with #GtkPlug, #GtkSocket provides the ability
-to embed widgets from one process into another process
-in a fashion that is transparent to the user. One
-process creates a #GtkSocket widget and, passes the
-that widget's window ID to the other process, 
-which then creates a #GtkPlug with that window ID.
-Any widgets contained in the #GtkPlug then will appear
-inside the first applications window.
-</para>
-
-<para>
-The socket's window ID is obtained by using
-gtk_socket_get_id(). Before using this function,
-the socket must have been realized, and for hence,
-have been added to its parent.
-
-<example>
-<title>Obtaining the window ID of a socket.</title>
-<programlisting>
-GtkWidget *socket = gtk_socket_new (<!-- -->);
-gtk_widget_show (socket);
-gtk_container_add (GTK_CONTAINER (parent), socket);
-
-/* The following call is only necessary if one of
- * the ancestors of the socket is not yet visible.
- */
-gtk_widget_realize (socket);
-g_print ("The ID of the sockets window is %#x\n",
-         gtk_socket_get_id (socket));
-</programlisting>
-</example>
-</para>
-
-<para>
-Note that if you pass the window ID of the socket to another
-process that will create a plug in the socket, you 
-must make sure that the socket widget is not destroyed
-until that plug is created. Violating this rule will
-cause unpredictable consequences, the most likely
-consequence being that the plug will appear as a 
-separate toplevel window. You can check if the plug
-has been created by examining the
-<structfield>plug_window</structfield> field of the
-#GtkSocket structure. If this field is non-%NULL, 
-then the plug has been successfully created inside
-of the socket.
-</para>
-
-<para>
-When GTK+ is notified that the embedded window has been
-destroyed, then it will destroy the socket as well. You
-should always, therefore, be prepared for your sockets
-to be destroyed at any time when the main event loop
-is running. To prevent this from happening, you can
-connect to the #GtkSocket::plug-removed signal.
-</para>
-
-<para>
-The communication between a #GtkSocket and a #GtkPlug follows the 
-<ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink>
-protocol. This protocol has also been implemented in other toolkits, e.g.  
-<application>Qt</application>, allowing the same level of integration
-when embedding a <application>Qt</application> widget in GTK or vice versa.</para>
-
-<para>
-A socket can also be used to swallow arbitrary 
-pre-existing top-level windows using gtk_socket_steal(),
-though the integration when this is done will not be as close
-as between a #GtkPlug and a #GtkSocket.</para>
-
-<note>
-<para>
-The #GtkPlug and #GtkSocket widgets are currently not available 
-on all platforms supported by GTK+.
-</para>
-</note>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-
-<varlistentry>
-<term>#GtkPlug</term>
-<listitem><para>the widget that plugs into a #GtkSocket.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><ulink url="http://www.freedesktop.org/standards/xembed-spec">XEmbed</ulink></term>
-<listitem><para>the XEmbed Protocol Specification.</para></listitem>
-</varlistentry>
-
-</variablelist>
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkSocket ##### -->
-<para>
-The #GtkSocket structure contains the <structfield>plug_window</structfield>
-field.  (This field should be considered read-only. It should
-never be set by an application.)
-</para>
-
-
-<!-- ##### SIGNAL GtkSocket::plug-added ##### -->
-<para>
-
-</para>
-
-@socket_: 
-
-<!-- ##### SIGNAL GtkSocket::plug-removed ##### -->
-<para>
-
-</para>
-
-@socket_: 
-@Returns: 
-
-<!-- ##### FUNCTION gtk_socket_new ##### -->
-<para>
-</para>
-
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_socket_steal ##### -->
-<para>
-</para>
-
-@socket_: a #GtkSocket.
-@wid: 
-
-
-<!-- ##### FUNCTION gtk_socket_add_id ##### -->
-<para>
-
-</para>
-
-@socket_: 
-@window_id: 
-
-
-<!-- ##### FUNCTION gtk_socket_get_id ##### -->
-<para>
-
-</para>
-
-@socket_: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_socket_get_plug_window ##### -->
-<para>
-
-</para>
-
-@socket_: 
-@Returns: 
-
-

diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index 847ee9ff0158e0986970c775ce14336c63f7e83d..3531af47fc759553870bfa0f08b482116df179ae 100644 (file)
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -41,6 +41,77 @@
 
 #include "gtkalias.h"
 
+/**
+ * SECTION:gtksocket
+ * @Short_description: Container for widgets from other processes
+ * @Title: GtkSocket
+ * @See_also: #GtkPlug, <ulink url="http://www.freedesktop.org/Standards/xembed-spec">XEmbed</ulink>
+ *
+ * Together with #GtkPlug, #GtkSocket provides the ability
+ * to embed widgets from one process into another process
+ * in a fashion that is transparent to the user. One
+ * process creates a #GtkSocket widget and passes
+ * that widget's window ID to the other process,
+ * which then creates a #GtkPlug with that window ID.
+ * Any widgets contained in the #GtkPlug then will appear
+ * inside the first application's window.
+ *
+ * The socket's window ID is obtained by using
+ * gtk_socket_get_id(). Before using this function,
+ * the socket must have been realized, and for hence,
+ * have been added to its parent.
+ *
+ * <example>
+ * <title>Obtaining the window ID of a socket.</title>
+ * <programlisting>
+ * GtkWidget *socket = gtk_socket_new (<!-- -->);
+ * gtk_widget_show (socket);
+ * gtk_container_add (GTK_CONTAINER (parent), socket);
+ *
+ * /<!---->* The following call is only necessary if one of
+ *  * the ancestors of the socket is not yet visible.
+ *  *<!---->/
+ * gtk_widget_realize (socket);
+ * g_print ("The ID of the sockets window is %#x\n",
+ *          gtk_socket_get_id (socket));
+ * </programlisting>
+ * </example>
+ *
+ * Note that if you pass the window ID of the socket to another
+ * process that will create a plug in the socket, you
+ * must make sure that the socket widget is not destroyed
+ * until that plug is created. Violating this rule will
+ * cause unpredictable consequences, the most likely
+ * consequence being that the plug will appear as a
+ * separate toplevel window. You can check if the plug
+ * has been created by using gtk_socket_get_plug_window(). If
+ * it returns a non-%NULL value, then the plug has been
+ * successfully created inside of the socket.
+ *
+ * When GTK+ is notified that the embedded window has been
+ * destroyed, then it will destroy the socket as well. You
+ * should always, therefore, be prepared for your sockets
+ * to be destroyed at any time when the main event loop
+ * is running. To prevent this from happening, you can
+ * connect to the #GtkSocket::plug-removed signal.
+ *
+ * The communication between a #GtkSocket and a #GtkPlug follows the
+ * <ulink url="http://www.freedesktop.org/Standards/xembed-spec">XEmbed</ulink>
+ * protocol. This protocol has also been implemented in other toolkits, e.g.
+ * <application>Qt</application>, allowing the same level of integration
+ * when embedding a <application>Qt</application> widget in GTK or vice versa.
+ *
+ * A socket can also be used to swallow arbitrary
+ * pre-existing top-level windows using gtk_socket_steal(),
+ * though the integration when this is done will not be as close
+ * as between a #GtkPlug and a #GtkSocket.
+ *
+ * <note>
+ * The #GtkPlug and #GtkSocket widgets are currently not available
+ * on all platforms supported by GTK+.
+ * </note>
+ */
+
 /* Forward declararations */
 
 static void     gtk_socket_finalize             (GObject          *object);